USBFindNextInterface

The USBFindNextInterface function is used to find an interface and its parent configuration. The USBFindNextInterface function searches through all configurations for interfaces matching the USB class, subclass, and protocol input parameters and returns both the number of the configuration it found the interface in, and the number of the matching interface. The interface numbers are returned in the order in which they appear in the configuration descriptor. You can iterate through the list of both configurations and interfaces until you find the interface you are looking for. The returned configuration information is used in the USBOpenDevice function call to set the device configuration containing the interface.

OSStatus USBFindNextInterface(USBPB *pb);

Required fields in the USBPB parameter block for the USBFindNextInterface function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

--> usbReference

Device reference

-- usbBuffer

Should be set to 0 (0 returned); reserved in this call

-- usbActCount

Should be set to 0 (0 returned); reserved in this call

-- usbReqCount

Should be set to 0 (0 returned); reserved in this call

--> usbFlags

Should be set to 0 (0 returned); reserved in this call

<--> usbClassType

--> Class, 0 matches any class <-- Class value for interface found

<--> usbSubclass

--> Subclass, 0 matches any subclass <-- Subclass value for interface found

<--> usbProtocol

--> Protocol, 0 matches any protocol <-- Protocol value for interface found

<--> usbWValue

Configuration number; start with 0

<--> usbWIndex

--> Interface number; start with 0 <-- Interface number

<--> usbOther

Alternate interface, set to 0xff to find first alternate only

For alternate interface settings, the usbOther field provides a method for getting details about a specific alternate interface or all of the alternate interfaces as a set. For example, the compound class driver would find all the interfaces in a device and load drivers for those interfaces. It would, however, treat the set of alternates as one interface and load only one driver for the alternate. That alternate driver would then have to determine what alternate settings were appropriate and choose the appropriate driver for those settings.

The value of 0 for usbClass, usbSubclass, or usbProtocol is a wildcard value that indicates the caller is interested in whatever information can be found for those parameters in the search. The actual values for any interface found are returned in those fields. If a driver wants to make a subsequent call using wildcards for the class, subclass, and protocol values, a 0 value must be explicitly passed in for the usbClass, usbSubclass, and usbProtocol fields, since the actual values for the interface found during the last call are returned in those fields of the parameter block.

The usbWValue and usbWIndex fields should be set to 0 upon first entry of the USBFindNextInterface function to indicate the search should start at the beginning of the configuration descriptors. For subsequent calls to the USBFindNextInterface function, the values returned in the usbWValue and usbWIndex fields should be passed back in without modification. The next interface matching the specified values will be found.

Errors returned by the USBFindNextInterface function include

paramErr		usbBuffer pointer, usbReqCount, or usbActCount fields are not set to 0
kUSBUnknownDeviceErr	-6998	usbReference does not refer to a current device
kUSBInternalErr, paramErr	-6999	internal configuration descriptor cache corrupted
kUSBNotFound	-6987	interface or configuration specified is not in configuration descriptors

USBOpenDevice

Once a suitable interface is found, the device is opened with the configuration specified in the USBOpenDevice function.

OSStatus USBOpenDevice(USBPB *pb);

Required fields in the USBPB parameter block for the USBOpenDevice function are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

--> usbReference

Device reference

-- usbBuffer

Should be set to 0 (0 returned); reserved in this call

-- usbActCount

Should be set to 0 (0 returned); reserved in this call

-- usbReqCount

Should be set to 0 (0 returned); reserved in this call

--> usbWValue

Configuration number

--> usbFlags

Should be set to 0

<-- usbOther

Number of interfaces in configuration

The configuration number is an arbitrary number assigned by the device to label the configurations. The number is usually sequential 1,2,3 and so on, but not guaranteed to be so.

Errors returned by the USBOpenDevice function include

paramErr		usbBuffer pointer, usbReqCount, or usbActCount fields are not set to 0
kUSBUnknownDeviceErr	-6998	usbReference does not refer to a current device
kUSBDeviceBusy	-6977	the device is already being configured
kUSBInternalErr, paramErr	-6999	internal configuration descriptor cache corrupted
kUSBNotFound	-6987	interface or configuration specified is not in configuration descriptors